home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
ShareWare OnLine 2
/
ShareWare OnLine Volume 2 (CMS Software)(1993).iso
/
prog
/
multi_c1.zip
/
MULTI_C.DOC
< prev
next >
Wrap
Text File
|
1992-11-08
|
59KB
|
2,311 lines
MULTI-APP V1.0.1
==============================
______________________________
==============================
Documentation Rev 0.3
Copyright 1992 by Jeff Heaton
MULTI-APP V1.0
A MicroGenesis Product
Copyright 1992 by Jeff Heaton
All Rights Reserved
MicroGenesis Software
P.O. Box No 25534
St. Louis, MO 63125
VOICE: (314) 638-2506
DATA:(314) 638-5205 n,8,1,1200-9600
Part I: The Multi-APP Core
Introduction
The MULTI-APP core is the heart of the MULTI-APP system. All classes
in the MULTI-APP system are derived from these "core classes." The
primary purpose of this core is to give all MULTI-APP classes a
consistent interface. Many abstract classes(who
se sole purpose is to define future classes) are defined here, as well
as real classes for file and data handling.
Using the MULTI-APP core you can provide your application with
platform-independent access to the basic system resources that all
applications need. These are the file system, the serial ports, and
basic data structure handling. In addition a spec
ial "error free" compression based communications protocol is provided
to allow you to access other MULTI-APP applications and share
information remotely.
In addition to providing these basic services, MULTI-APP core allows
you to use the MULTI-APP user interface package to produce GUI(graphic
user interface) applications in a platform-independent manner.
MultiApp Core Features:
I. Platform Independent Access to Files:
A. DEVICE compatible for I/O redirection
B. Allows concurrent shared access of files
C. Buffered character access provides maximum speed
D. Fast block read/write functions for record handling
II. Platform Independent Access to Serial Ports:
A. DEVICE compatible for I/O redirection
B. Optional Compression/Error correction(in SOFTWARE)
C. Access to all hardware lines provided by host computer
III. Misc Platform Independent Services:
A. Integer stacks
B. Base classes for linked lists
C. File Maintenance functions
License
The MultiApp system is currently being marketed as ShareWare.
Shareware is a unique software distribution method where you, the
software user, gets to try out the program BEFORE you pay for it. This
is a FULL version of the MultiApp core, and you
get a FULL copy of the text representation of the user manual to
evaluate for a time period of 30(thirty) days. If you wish to continue
using MultiApp after this trial period, or if you publicly release a
program(commercial,shareware, public domain
or any other non-personal use) you MUST register your copy. Upon
registration you will receive the complete source code to the MultiApp
product that you registered. The source code, however, will be for
your exclusive use and may not be distributed
directly. However, applications can be created using source code
modifications.
If you use MultiApp beyond the initial 30 day limit, or publicly
release any application that contains MultiApp code you MUST have
registered MultiApp. To do otherwise is a direct violation of the
MultiApp copyright. However once you have register
ed a MultiApp product you may use it in your own application, royalty
free, for as many applications as you wish.
The following information is not in classes and provide miscellaneous
utility to the MULTI-APP system. Some of the data structures defined
here are only used in the MULTI-APP user interface and are thus only
briefly described.
Contacting MicroGenesis:
Compuserve : 76476,1701
America On-Line : JeffH66
InterNet : S108955@UMRVMA.UMR.EDU
Voice : (314) 638-2506
BBS : (314) 638-1731
Compiler Considerations:
If you want to maximize portablilty between various computer platforms
MultiApp can greatly speed this process. However because even C/C++
compilers interpret the C/C++ standard differently you must account for
these differences in your code. Thes
e are generally only syntactical errors that will show up when you
compile your application on another platform for the first time.
MultiApp does not use pure c++ as its coding standard. Pure C++ can
defiantly be used with MultiApp but since many platforms(particularly
the Macintosh) are lacking in the area of quality C++ compilers we have
developed MultiApp based on a simpler
subset of C++. This is based on Symantec Think C 5's objects
extension. This is basically identical to C++ but without some of
C++'s more complex features. IF you want your application to be
directly compilable on object based C compilers you shou
ld not use the following C++ features:
Function Overloading
Operator Overloading
Function Templates
Parameters To Constructors
Static Objects(ie MYOBJECT obj; is illegal it MUST be
MYOBJECT *obj)
this redefinition(this=this->next is illegal, all other standard this
operations are legal however).
All Functions MUST have prototypes.
Cast all pointer conversions
These are some general rules to follow to ensure that your programs
are compatible with Object C type compilers as well as True C++
compilers. Once multiApp is ported into C++ compilers on both Dos and
Mac these restrictions will not be necessary.
We are currently working on creating a MPW version of MutliApp that
will support full C++, but for now please remember that not all
platforms have as "developed" of a base of C++ compilers as the IBM
platform does.
If you are going to be seriously developing cross-platform
applications than it is suggested that you own a copy of BOTH
Borland/Turbo C++ and Think C so you can see the differences for
yourself. I have not found it to be too much of a problem in o
ur own development. Just treat Think C as the "least common
denominator" and you will do fine. We will also be coming out with a
document further describing Think C/Borland C++ compatibility with the
release of MultiApp UI.
Global Functions:
void beep(void);
This function will cause the users computer to beep.
void c2pas(char *str);
This function will transform str into a pascal string(assuming it was
originally a c string).
void pas2c(char *str);
This function will transform str into a c string(assuming it was
originally a pascal string).
void sleep(int tenths);
This function will wait for tenths 1/10ths of a second.
int timer_check(long tm);
Call this function,with the value timer_set returns, to see if the
time is up. If that time has elapsed then this function returns true.
long timer_set(int tenths);
Sets a timer for tenths 1/10ths of a second. The value that this
function returns should be passed to timer_check to determine if that
time has elapsed.
void timer_wait(long tm);
Call this function with the value timer_set returns to wait until that
amount of time elapses.
void updcrc(unsigned char b);
Each call of this function causes b to be calculated into the global
crc.
extern unsigned short crc;
This variable is used with updcrc to calculate a CRC value. After
you are done feeding updcrc your bytes, this is the variable you get
your final CRC from.
Definitions:
The following are some general integer to binary conversion functions
that allow MULTI-APP data to be compatible across platforms(especially
since Intel and Motorola store ints exactly backwards of each other):
#define HI_BYTE(x) (x/256)
#define LO_BYTE(x) (x-(HI_BYTE(x)*256))
#define BYTE_COMB(x,y) ((x*256)+y)
CLASS NAME: ATOM PARENT: NONE
IMPORTANT CHILDREN: almost the whole library.
Definition:
class ATOM
{
public:
ATOM();
ATOM *next;// Next atom in a linked list
};
Description:
The most fundamental class of MULTI-APP is the atom class. Every
object in the MULTI-APP library is derived from the atom class. This
allows general purpose "data container classes" to be defined for the
atom. These data container classes can
then be used for other object types as well. The most important of
these data container classes is the linked list class(LIST). In its
simplest form LIST allows a linked list of ATOM's, but because WINDOW
classes are derived from ATOM it is possibl
e to create a linked list of WINDOWs or any other descendant of the
ATOM class.
Member Functions:
ATOM();
Description:
CONSTRUCTOR - simply sets next equal to NULL.
Returns:
nothing
See Also:
Example:
int search_for(ATOM *first,ATOM *lookfor)
{
// Search the linked list pointed to by "first" for
// "lookfor". Return TRUE if found
while(first!=NULL)
{
if(first==lookfor)// Found it yet?
return TRUE;
first=first->next;// Next atom in list
}
}
Data Members:
ATOM *next;
The next ATOM in the linked list.
CLASS NAME: LIST PARENT: ATOM
IMPORTANT CHILDREN: APP(from the user interface)
Definition:
class LIST:public ATOM
{
public:
LIST(void);
void add(ATOM *atom);
void del(ATOM *atom);
void first_element(void);
void forward(void);
void pos(long p);
virtual int comp(ATOM *a1,ATOM *a2);
ATOM *first,*current;
};
Description:
The LIST object is one of the primary classes of MULTI-APP. LIST is a
"data container object" designed to hold a linked list of ATOMS.
Because almost every object in MULTI-APP is derived from ATOM, lists
can be built of many different types of obj
ects. For example in the MULTI-APP User Interface section you will
learn that the APP class is really a linked list of all open windows.
Because APP is a child of LIST it can build lists of ANYTHING that is
derived from ATOM. This includes windows
, dialogs and many other types of screen objects.
Data Members:
ATOM *first;
This is the first ATOM in the linked list. This gives LIST a
starting point for list resets and searches. If the list is empty then
this variable contains a NULL.
ATOM *current;
Current is the atom that the list is currently processing. It is
perfectly legal for current to be NULL, even if the list has data in
it. A NULL current usually means that you have reached the end of the
list.
Member Functions:
LIST(void);
Description:
CONSTRUCTOR - This sets current and first to NULL, thus creating a
new blank LIST.
Returns:
nothing
See Also:
ATOM
Example:
void main(void)
{
LIST *list;// The list we will be adding items to
ATOMS *a,*b,*c; // Some atoms to add
list=new LIST;
list->add(a=new ATOM);
list->add(b=new ATOM);
list->add(b=new ATOM);
// At this point the list would look something like:
// a-->b-->c-->NULL
list->del(b);
// At this point the list would look something like:
// a-->c-->NULL
// Now loop through the list
first_element();
while(current!=NULL)
forward();
}
_________________________________________________________
void add(ATOM *atom);
Description:
atom - The atom being added to list.
This function adds a new ATOM into the list. The comp function is
used to determine atom's position. If comp is not redefined then the
atom is inserted at the end of the list.
Returns:
nothing
See Also:
del
Example for LIST class.
Example:
void MYOBJECT::add(ATOM *atom)
{// An add function for a derived LIST manager
MYITEM *i=(MYITEM*)atom;
// Now use "i" to officially add your type of object
// This is usually some sort of inititilaztion
LIST::add(atom);// Add it to the actual list
}
_________________________________________________________
virtual int comp(ATOM *a1,ATOM *a2);
Description:
a1 - The atom on the left side of the comparison
a2 - The atom on the right side of the comparison
This function compares a1 to a2 and returns:
0 Both ATOMS are equal.
>1 a1 is greater than a2
<1 a2 is greater than a1
Comp is used to sort ATOMS as they enter the list.
Returns:
nothing
See Also:
forward()
Example for LIST class.
Examples:
// A compare function(the default) that will insert items into the
list in reverse order.
int class::comp(ATOM *a1,ATOM *a2){ return 1; }
// A compare function that will insert items in the same order they
are entered
int class::comp(ATOM *a1,ATOM *a2){ return -1; }
_________________________________________________________
void del(ATOM *atom);
Description:
atom - The atom being removed from the list.
This function removes an ATOM from the list. Please note that the
memory for atom is not freed, but rather the ATOM is simply pulled out
of the list chain.
Returns:
nothing
See Also:
add
Example for LIST class.
Example:
void MYOBJECT::del(ATOM *atom)
{// An del function for a derived LIST manager
MYITEM *i=(MYITEM*)atom;
// Now use "i" to officially remove your type of object
// This is usually some sort of shutdown sequence
LIST::del(atom);// Add it to the actual list
}
_________________________________________________________
void first_element(void);
Description:
This function sets current to first, thus moving the lists attention
to its first element. This function is usually called prior to a
search.
Returns:
nothing
See Also:
forward()
Example for LIST class.
_________________________________________________________
void forward(void);
Description:
This function moves the current pointer to the next ATOM in the list.
If there are no more ATOMs or the list is empty then current is set
to NULL.
Returns:
nothing
See Also:
first_element()
Example for LIST class.
_________________________________________________________
void pos(long p);
Description:
p - element in list to move to.
This function moves(points current to) the "p"th element in the
linked list.
Returns:
nothing
See Also:
forward
CLASS NAME: DEVICE PARENT: LIST
IMPORTANT CHILDREN: FILEIO, and any device class made for MULTI-APP
Definition:
class DEVICE:public LIST
{
public:
virtual int put(BYTE ch);
virtual int putstr(char *str);
virtual int goxy(int x,int y);
virtual int inverse(void);
virtual int normal(void);
virtual BYTE get(BYTE *ch);
virtual BYTE wait2get(BYTE *ch);
virtual int hit(void);
virtual int reset(void);
virtual int ceol(void);
virtual int wherex(void);
virtual int wherey(void);
virtual int printf(char *format,...);
int getstr(char *str);
};
Description:
DEVICE is a object that defines basic properties that any MULTI-APP
compatible device should have. DEVICE allows MULTI-APP to communicate
to a device in a polled 8-bit manner. Commands are provided to do
basic byte I/O as well as some general cont
rol commands that many "video" devices would have. The commands
provided here are the same on ALL the children of DEVICE. So as a
result the command to print a string is identical in all parts of
MULTI-APP.
Data Members:
NONE
Member Functions:
virtual int ceol(void);
Description:
Ceol is only used in video devices, it will clear to the end of the
line starting at wherex,wherey.
Returns:
nonzero on error.
See Also:
reset.
_________________________________________________________
int getstr(char *str);
Description:
str - the string read from the device.
This function will input characters into the string str until a
carriage return(#13) is received. The final carriage return is not
stored in the string. If the operation is successful this function will
return a zero.
Returns:
nonzero on error.
See Also:
_________________________________________________________
virtual BYTE get(BYTE *ch);
Description:
ch - if NULL does nothing, otherwise the BYTE read.
This function receives the next 8-bit character from the device. If
none are available then this function returns a zero. There are two
paths by which this function returns its data. First is through the
normal function return, and second is via
a pointer to a BYTE. If you do not wish to use the pointer method
simply call it as "get(NULL)". Example: "x=get(NULL)", "get(&x)" and
"x=get(&x)" all do exactly the same thing.
Returns:
character read, or a zero if none are available.
See Also:
put,getstr,wait2get,hit.
Example:
BYTE DEVICE::wait2get(BYTE *ch)
{
BYTE c;
while(!hit());// Loop until something is available
c=get(NULL);// Input character
if(ch!=NULL)// Return by pointer if necessary
*ch=c;
return(c);
}
_________________________________________________________
virtual int goxy(int x,int y);
Description:
x - The horizontal position to goto.
y - The vertical position to goto.
This function allows you to set the x and y coordinates of the
device. Not all devices have x/y coordinates, so this function is not
used in all DEVICES. If the operation is successful this function will
return a zero.
Returns:
nonzero on error.
See Also:
reset.
Example:
void home(DEVICE *d)
{// Home the cursor in any device(if it supports cursors)
d->goxy(0,0);
}
_________________________________________________________
virtual int hit(void);
Description:
Hit allows you to determine if there is a character waiting to be
received(by one of the input functions). Hit returns 0 if none are
available. If data is waiting it returns the number of bytes waiting.
Returns:
true if there is a character waiting to be read.
See Also:
get,wait2get.
Example:
see get.
_________________________________________________________
virtual int inverse(void);
Description:
If the device is capable of having its foreground and background
colors inverted this function inverses them. If the operation is
successful then this function will return a zero. Inverse is left
over from before MULTI-APP supported color, and i
s rarely used anymore.
Returns:
nonzero on error.
See Also:
normal.
_________________________________________________________
virtual int normal(void);
Description:
This function resets any special modes(namely inverse) that may have
been set on this device. If the operation is successful this
function will return a zero.
Returns:
nonzero on error.
See Also:
inverse.
_________________________________________________________
virtual int printf(char *format,...);
Description:
format - "stdio.h printf" format string to write.
This output function allows you to output to a device in the classic
C printf style. Consult your C reference manual if you require
additional information on printf. Please note that the final outputted
string cannot be larger than 199 characters
, if it is the results are undefined.
Returns:
nonzero on error.
See Also:
put,putstr.
Example:
void main(void)
{
DEVICE *device;
device=new DEVICE;
device->goxy(10,10);// Move cursor
device->printf("Cursor is at: %xi,%i.",// Display cursor's location
device->wherex(),device->wherey());
}
_________________________________________________________
virtual int put(BYTE ch);
Description:
ch - the character to be written.
This function will attempt to write a single character to the device.
If the operation is successful this function will return a zero.
Returns:
nonzero on error.
See Also:
putstr,printf.
Example:
void spc(DEVICE *device,int i)
{// write out i spaces(32) to any type of device
while(i--)
d->put(32);
}
_________________________________________________________
virtual int putstr(char *str);
Description:
str - the string to be written.
This function repeatedly calls put until a zero is reached in the
string. If the operation is successful this function will return a
zero.
Returns:
nonzero on error.
See Also:
put,printf
Example:
int DEVICE::printf(char *format, ... )
{// The printf function from DEVICE
char string[200];
va_list ptr;
va_start(ptr,format);
vsprintf(string,format,ptr);
putstr(string);
va_end(ptr);
return 0;
}
_________________________________________________________
virtual int reset(void);
Description:
Reset acts very different based on the device. On most video devices
it will clear the screen, while on others it flushes all I/O buffers.
Returns:
nonzero on error.
See Also:
goxy.
_________________________________________________________
virtual BYTE wait2get(BYTE *ch);
Description:
ch - if NULL does nothing, otherwise the BYTE read.
This function enters a loop to wait for a character to be available
then receives the next 8-bit character from the device. There are two
paths by which this function returns its data. First is through the
normal function return, and second is vi
a a pointer to a BYTE. If you do not wish to use the pointer method
simply call it as "get(NULL)". Example: "wait2get(NULL)",
"wait2get(&x)" and "x=wait2get(&x)" all do exactly the same thing.
WARNING: This function can hang the system if no char
acter ever becomes available.
Returns:
character read.
See Also:
put,getstr,hit.
Example:
see get.
_________________________________________________________
virtual int wherex(void);
Description:
The wherex function will return the x coordinate of this device.
Returns:
nonzero on error.
See Also:
wherey,reset,goxy.
Example:
void main(void)
{
DEVICE *device;
device=new DEVICE;
device->goxy(10,10);// Move cursor
device->printf("Cursor is at: %xi,%i.",// Display cursor's location
device->wherex(),device->wherey());
}
_________________________________________________________
virtual int wherey(void);
Description:
The wherey function will return the y coordinate of this device.
Returns:
nonzero on error.
See Also:
wherex,reset,goxy.
Example:
void main(void)
{
DEVICE *device;
device=new DEVICE;
device->goxy(10,10);// Move cursor
device->printf("Cursor is at: %xi,%i.",// Display cursor's location
device->wherex(),device->wherey());
}
CLASS NAME: COMIO PARENT: DEVICE
IMPORTANT CHILDREN: ALP
Definition:
class COMIO:public DEVICE
{
public:
COMIO(void);
~COMIO();
int init(int p);
virtual int put(BYTE ch);
virtual BYTE get(BYTE *ch);
virtual int putstr(char *str);
virtual int hit(void);
virtual void baud(long r);
virtual void disconnect(void);
virtual int timed_get(BYTE *ch,int secs);
void flush_out(void);
void flush_in(void);
void purge_out(void);
void purge_out(void);
void flow(int i);
void dtr(int i);
char carrier(void);
int direct,no_modem;
long lockbaud;
long baudrate,bps;
private:
Varies with operating system.
};
Description:
COMIO provides a platform-independent method for communicating with
the computer's serial ports. COMIO follows the strict interface
definition defined by the DEVICE class, and is consistent with all
other MULTI-APP classes in that way. You can spec
ify many additional arguments that are compatible only with a serial
device, yet all serial I/O is compatible with the DEVICE class.
Hardware comport numbers always start at 1.
Data Members:
long baudrate
The baud rate that the remote modem is at, regardless of locked
baudrate. This must be maintained by the user if it is needed.
long bps
The port's baud rate, if baud rate is locked then this should never
be different than lockbaud. This value is set internally by MultiApp
and is meant for reference only.
char detect_carrier
If this value is true then the carrier function returns the status
of the carrier pin. If this value is false then carrier always returns
true.
int direct
If this value is one then the COMIO object will do all of its
communication at the most direct level possible. On Mac this would be
through the serial manager, on Dos this would mean through interrupts
and ports. If this value is zero then the C
OMIO object will do all of its communication at a higher level. On Mac
this would still be through the serial manager, on dos this would be
through BIOS or a FOSSIL if one is loaded. Generally you should set
this as 1. WARNING: never change this
value once init has been called.
long lockbaud
This variable allows you to lock the baud rate at some speed. If
you set it to zero(the default) then baud rate is variable. Some 9600
baud modems require their baud rate to be locked at 38,400 baud, this
function makes the use of such modems ea
sier.
int no_modem
If this variable is set to one then no communication with the serial
ports is made. This provides for a sort of test mode.
port
Serial port number that this instance of COMIO is working with.
Member Functions:
COMIO(void);
Description:
CONSTRUCTOR - Allocates any memory needed for buffers.
Returns:
nothing.
See Also:
~COMIO.
Example:
// VTERM is a simple tty terminal that must be provided with a DEVICE
to use
// as a console. This console is usually something such as the UI's
CONIO object
// however it can really be anything, even another COMIO(which would
provide a
// remote terminal. Press \ for a list of commands in this terminal.
void vterm(DEVICE *con,COMIO *com)
{
// con - console device
// com - "modem" interface
int done=0;
char ch;// Check for commands
com->baud(2400);// Default to 2400 baud
while(!done)
{
if(con->hit())// Output keypress
{
ch=con->get(NULL);
if(ch!='\')
com->put(con->get(NULL));
}
if(com->hit())// Display incoming data
con->put(com->get(NULL));
if(ch=='\')
{
char str[100];
con->reset();
con->putstr("Select an option: <B>aud <D>isconnect or <Q>uit? ");
switch( toupper(con->wait2get(NULL)))
{
case Q':done=1;break;
case D':com->disconnect();break;
case B':con->putstr("\rWhat baud? ");
con->getstr(str);
con->baud(atoi(str));
break;
}
}
}
}
_________________________________________________________
~COMIO();
Description:
DESTRUCTOR - Releases any allocated memory, and closes the hardware
serial port.
Returns:
nothing.
See Also:
COMIO.
_________________________________________________________
virtual void baud(long r);
Description:
r - The baud rate that you wish to use.
Commands the hardware comport to do all I/O at r baud rate.
Returns:
nonzero on error.
See Also:
init.
Example:
see constructor example.
_________________________________________________________
virtual void baud(long r);
Description:
r - The baud rate that you wish to use.
Commands the hardware comport to do all I/O at r baud rate.
Returns:
nonzero on error.
See Also:
init.
Example:
see constructor example.
_________________________________________________________
virtual void disconnect(void);
Description:
This function is intended for when the serial port is connected to a
hayes compatible modem. Disconnect attempts to break the connection
by dropping DTR, if that doesn't work then the classic +++ followed
by ATH is sent.
Returns:
nonzero on error.
See Also:
dtr.
Example:
see constructor example.
_________________________________________________________
void dtr(int i);
Description:
i - State of DTR:1=on, 0=off.
This function allows you to set the state of the DTR line. Call it
with 1 to raise DTR, zero to lower DTR.
Returns:
nothing.
See Also:
Example:
void COMIO::disconnect()
{
int i;
dtr(0);// Attempt to disconnect using DTR
sleep(30);
dtr(1)
if(!carrier())// If no carrier then we are done
return;
for(i=0;i<=2;i++)
{
COMIO::put('+');
sleep(30);
}
sleep(15);
COMIO::putstr("\rATH0\r");
}
_________________________________________________________
void flush_in(void);
Description:
This function will clear out the current inbound buffer, and any
characters that may arrive while clearing. It will not return until
the hit function returns a zero.
Returns:
nothing
See Also:
flush_out,purge_in,purge_out
_________________________________________________________
void flush_out(void);
Description:
This functions for the operating system to transmit any characters
waiting in the out buffer.
Returns:
nothing.
See Also:
flush_in,purge_in,purge_out
_________________________________________________________
virtual BYTE get(BYTE *ch);
Description:
ch - Pointer to where to store read character(if not NULL).
This function receives the next 8-bit character from the serial port.
If none are available then this function returns a zero. There are two
paths by which this function returns its data. First is through the
normal function return, and second i
s via a pointer to a BYTE. If you do not wish to use the pointer
method simply call it as "get(NULL)". Example: "x=get(NULL)",
"get(&x)" and "x=get(&x)" all do exactly the same thing.
Returns:
character read.
See Also:
put,getstr,hit.
Example:
see constructor example.
_________________________________________________________
virtual int hit(void);
Description:
Hit allows you to determine if there is a character waiting to be
received(by one of the input functions). Hit returns 0 if none
available. If data is waiting it returns the number of bytes waiting.
Returns:
true if there is a character available.
See Also:
get,wait2get.
Example:
see constructor example.
_________________________________________________________
int init(int p);
Description:
p - the comport that you want to use.
Opens hardware comport p and attaches it to this object.
Returns:
nonzero on error.
See Also:
~COMIO.
Example:
see constructor example.
_________________________________________________________
void purge_in(void);
Description:
This function will erase any characters that are currently in the
input buffer.
Returns:
nothing
See Also:
flush_in,flush_out,purge_out
_________________________________________________________
void purge_out(void);
Description:
This function removes any characters from the output buffer, causing
them to never be transmitted.
Returns:
nothing.
See Also:
flush_out,flush_in,purge_in
_________________________________________________________
virtual int put(BYTE ch);
Description:
ch - the character to be written.
This function will attempt to write a single character to the device.
If the operation is successful this function will return a zero.
Returns:
nonzero on error.
See Also:
get,putstr,printf.
Example:
see constructor example.
_________________________________________________________
int putstr(char *str);
Description:
str - the string or modem command.
This function is used primarily for modem commands. If the string
starts with the letters AT then the string is assumed to be a modem
command and some extra processing is done. Otherwise the string is
simply written to the serial port. Modem str
ings may have the following characters imbedded in them:
| (pipe) = carriage return
{ = carriage return
v(lowercase)= drop dtr
^(carrot) = raise dtr
Returns:
zero on success.
See Also:
_________________________________________________________
virtual int timed_get(BYTE *ch,int secs);
Description:
ch - pointer to where to store read character.
secs-how many tenths of a second to wait for the character.
This function receives the next 8-bit character from the serial port.
If none are available then this waits secs 1/10ths of a seconds for one
to arrive. If a character was found before timeout this function
returns 0, otherwise a one is returned.
The actual character is returned by the ch pointer.
Returns:
nonzero on error.
See Also:
CLASS NAME: ALP PARENT: COMIO
IMPORTANT CHILDREN: none
Definition:
struct ALP:public COMIO
{
public:
ALP();
void update(void);// Call this as often as possible
void intr(void);
int check(void); // Check for ALP-compat device on remote side
void transmit(void); // transmit a packet
// Replacements for CONIO functions:
virtual int put(BYTE ch);
virtual BYTE get(BYTE *ch);
virtual int hit(void);
virtual void disconnect();
char str[2000];
int p;
BYTE intrans;
BYTE no_alp;
private:
// Incoming queue
void push(BYTE ch);
BYTE pop(void);
void input(BYTE ch);
BYTE hi,lo;
BYTE in_packet[2048];
BYTE uncomp[2048];
BYTE phase;
int in_length;
int in_num;
unsigned short in_crc;
unsigned short in_tcrc;
int in_loc;
BYTE queue[ALP_IN];
int front,back;
int background;
BYTE outnum;
BYTE lastnum;
};
Description:
ALP(Anti Line noise Protocol) is a replacement for COMIO that ensures
a 2-way reliable serial connection. Data is sent out in packets(which
are compressed using the LZSS protocol) that are verified to insure a
reliable link. It is 100% compatible
with the COMIO object. This communications standard allows separate
MULTI-APP applications to have a common hi-level method of
communication. When using ALP you can use put,get and all the other
COMIO functions and let ALP worry about the error che
cking. Except for the update function none of the additional contents
of this class are of any real use to the application programmer.
Data Members:
BYTE intrans;
Intrans is a flag that tells if a packet is in transit or not. If a
packet is in-transit it means that the packet has been sent, yet ALP is
unsure if it made it through correctly or not. Intrans holds 1 if
block is in transit, zero if not.
BYTE no_alp;
no_alp is a flag that tells if ALP is enabled or not. If ALP is
disabled then all calls are passed directly through to the COMIO
object.
int p;
P tells ALP how many characters are in the str buffer waiting to go
out in the next packet. See str for more details.
char str[2000];
This is the buffer where outgoing data is held until it is packeted.
This variable is made public because it is perfectly legal to memcopy
stuff into str and modify p directly. This is particularly appealing
in file transfer situation as it cuts
the overhead induced by the COMIO replacements.
Member Functions:
ALP();
Description:
CONSTRUCTOR - The ALP constructor sets up all buffers and initialized
all pointers.
Returns:
nothing.
See Also:
Example:
// VTERM-ALP is a simple tty terminal that must be provided with a
DEVICE to use
// as a console. This console is usually something such as the UI's
CONIO object
// however it can really be anything, even another COMIO(which would
provide a
// remote terminal. Press \ for a list of commands in this terminal.
// This example is very similar to the example given in COMIO, this
shows how
// compatible these two classes are.
void vterm(DEVICE *con,ALP *com)
{
// con - console device
// com - "modem" interface
int done=0;
char ch;// Check for commands
com->baud(2400);// Default to 2400 baud
while(!done)
{
com->update();// For ALP to packet everything when needed
if(con->hit())// Output keypress
{
ch=con->get(NULL);
if(ch!='\')
com->put(con->get(NULL));
}
if(com->hit())// Display incoming data
con->put(com->get(NULL));
if(ch=='\')
{
char str[100];
con->reset();
con->putstr("Select an option: <B>aud <D>isconnect,<A>lp or
<Q>uit? ");
switch( toupper(con->wait2get(NULL)))
{
case Q':done=1;break;
case D':com->disconnect();break;
case B':con->putstr("\rWhat baud? ");
con->getstr(str);
con->baud(atoi(str));
break;
case A':
if(com->check())
con->putstr("ALP active\r");
break;
}
}
}
}
_________________________________________________________
int check(void);
Description:
This function is used to establish an ALP session. Check transmits
the ALP init string and waits for a reply. If the other side
replies(it does this automatically via update) then both sides no_alp
values gets set to zero and an ALP session begi
ns.
Returns:
TRUE if ALP link has been established.
See Also:
update,intr.
Example:
see constructor example.
_________________________________________________________
virtual void disconnect(void);
Description:
This function is intended for when the serial port is connected to a
hayes compatible modem. Disconnect first ends the ALP session. Then
disconnect attempts to break the connection by dropping DTR, if that
doesn't work then the classic +++ follow
ed by ATH is sent.
Returns:
nothing.
See Also:
dtr.
Example:
see constructor example.
_________________________________________________________
void dtr(int i);
Description:
i - State of DTR:1=on, 0=off.
This function allows you to set the state of the DTR line. Call it
with 1 to raise DTR, zero to lower DTR.
Returns:
nothing.
See Also:
Example:
void COMIO::disconnect()
{
int i;
dtr(0);// Attempt to disconnect using DTR
sleep(30);
dtr(1)
if(!carrier())// If no carrier then we are done
return;
for(i=0;i<=2;i++)
{
COMIO::put('+');
sleep(30);
}
sleep(15);
COMIO::putstr("\rATH0\r");
}
_________________________________________________________
void flow(int i);
Description:
i - flow control type:
0 = NONE
1 = CTS/RTS(hardware)
2 = XON/XOFF(software)
3 = both hardware and software
This function sets the flow control mode of the serial port. This is
useful for high speed modems.
Returns:
nothing.
See Also:
_________________________________________________________
virtual BYTE get(BYTE *ch);
Description:
ch - Pointer to where to store read character(if not NULL).
This function receives the next 8-bit character from the ALP driver.
If none are available then this function returns a zero. There are two
paths by which this function returns its data. First is through the
normal function return, and second is
via a pointer to a BYTE. If you do not wish to use the pointer method
simply call it as "get(NULL)". Example: "x=get(NULL)", "get(&x)" and
"x=get(&x)" all do exactly the same thing.
Returns:
the character read.
See Also:
getstr,put,hit.
Example:
see constructor example.
_________________________________________________________
virtual int hit(void);
Description:
Hit allows you to determine if there is a character waiting to be
received(by one of the input functions). Hit returns 0 if none
available. If data is waiting it returns the number of bytes waiting.
Returns:
the number of characters waiting to be read.
See Also:
get.
Example:
see constructor example.
_________________________________________________________
void intr(void);
Description:
Intr is similar to update, except that it is intended to be called
from an interrupt if that is how you desire to make sure ALP stays
updated.
Returns:
nothing.
See Also:
update.
_________________________________________________________
virtual int put(BYTE ch);
Description:
ch - character to be written.
This function will attempt to write a single character to the device.
If the operation is successful this function will return a zero.
Returns:
nonzero on error.
See Also:
printf,putstr.
Example:
see constructor example.
_________________________________________________________
void transmit(void);
Description:
Transmit will force a packet to be transmitted.
Returns:
nothing.
See Also:
_________________________________________________________
void update(void);
Description:
Update should be called as often as possible, as it checks the
incoming data line for packets and transmits any waiting data in a
packet.
Returns:
nothing.
See Also:
intr.
Example:
see constructor example.
CLASS NAME: FILEIO PARENT: DEVICE
IMPORTANT CHILDREN: none
Definition:
class FILEIO:public DEVICE
{
public:
FILEIO();
~FILEIO();
int gethandle(void);
void open_file(char *path,char *name,char md,char *type,char
*creator);
void fread(void *loc,long len);
void fwrite(void *loc,long len);
char end(void);
char error(void);
void close_file(void);
void pos(long loc);
long where(void);
virtual int put(BYTE ch);
virtual BYTE get(BYTE *ch);
char sharing;
char filename[80];
};
Description:
FILEIO provides a platform-independent method for accessing files. It
is setup exactly like any other MGBBS DEVICE. Support is provided for
file sharing(in platforms that support it). All single character
commands are buffered to provide maximum
speed.
Data Members:
char sharing;
Holds 1 if file sharing is on, 0 if it is off(set by user).
char filename[80];
Holds the full file name(including path).
Member Functions:
FILEIO();
Description:
CONSTRUCTOR - sets up all pointers, handles etc.
Returns:
nonzero on error.
See Also:
Example:
int copyfile(char *source_path,char *source_name,char
*dest_path,char *dest_name)
{// This function will copy a file. Please note that this function
will only copy the
// data fork of a Macintosh File.
FILE *in,*out;
in=new FILEIO;
out=new FILEIO;
in->open_file(source_path,source_name,'r',"","");
out->open_file(dest_path,dest_name,'w',"","");
if(in->error() || out->error() )
{
delete in;// Delete both file objects(this will close either if
they were opened)
delete out;
return 1;// return an error condition
}
while(!in->end())// Loop until end-of-file is reached
out->put(in->get(NULL));
in->close_file();
out->close_file();
}
_________________________________________________________
~FILEIO();
Description:
DESTRUCTOR - closes file if open.
Returns:
nonzero on error.
See Also:
_________________________________________________________
void close_file(void);
Description:
This function will close the file, allowing the same data structure
to be used for another file.
Returns:
nonzero on error.
See Also:
_________________________________________________________
char end(void);
Description:
This function returns true if the end of the file has been reached.
Returns:
nonzero on error.
See Also:
_________________________________________________________
char error(void);
Description:
This function returns true if the file is in an error condition.
Returns:
nonzero on error.
See Also:
_________________________________________________________
void fwrite(void *loc,long len);
Description:
loc - The location in memory your writing from.
len - The length of the block being written.
This function, which is similar to the <stdio.h> function of the same
name, allows you to write something pointed to by loc of length len to
the file.
Returns:
nonzero on error.
See Also:
_________________________________________________________
void fread(void *loc,long len);
Description:
loc - Pointer to the location in memory to hold block
len - The length of the file you wish to read.
This function, which is similar to the <stdio.h> function of the same
name, allows you to read something into an area pointed to by loc of
length len from the file.
Returns:
nonzero on error.
See Also:
_________________________________________________________
virtual BYTE get(BYTE *ch);
Description:
ch - Pointer to where to store read character(if not NULL).
This function receives the next 8-bit character from the device. If
none are available then this function returns a zero. There are two
paths by which this function returns its data. First is through the
normal function return, and second is via
a pointer to a BYTE. If you do not wish to use the pointer method
simply call it as "get(NULL)". Example: "x=get(NULL)", "get(&x)" and
"x=get(&x)" all do exactly the same thing.
Returns:
nonzero on error.
See Also:
_________________________________________________________
int gethandle(void);
Description:
Most operating systems use a single integer to reference a file. If
the operations system your using MULTI-APP in supports such file
referencing this function returns that value. Use of this function
should be avoided, as it can cause code created
for MULTI-APP to be incompatible on other platforms.
Returns:
nonzero on error.
See Also:
_________________________________________________________
void open_file(char *path,char *name,char md,char *type,char
*creator);
Description:
path - The location in the file system of the file.
name - The actual name of the file.
md - The access mode your using for the file.
type - The 4 character file type(only used on some OS's)
mode - The 4 character file signature(only used on some OS's)
This function is used to tell FILEIO which fill it will be accessing.
You can specify both a path and a name. md should be one of the
following:
r' for reading(other users are allowed to also read)
w' for writing and truncation(other users must wait to access file)
+' both read and write(other users must wait to access file)
s' for both read/write(other uses may have full access to file)
a' for appended write(other users must wait to access file)
The type and creator allow you to specify these fields if your
operating system supports them. The w' command will erase anything
that was in the file beforehand. If you wish to write a single
record in a file you must open with the +' command, e
ven if you will not be reading.
Returns:
nonzero on error.
See Also:
_________________________________________________________
void pos(long loc);
Description:
loc - Location in bytes to place file pointer.
This function will position the file position at loc.
Returns:
nonzero on error.
See Also:
_________________________________________________________
virtual int put(BYTE ch);
Description:
ch - The character to be written to the file.
This function will attempt to write a single character to the device.
If the operation is successful this function will return a zero.
Returns:
nonzero on error.
See Also:
_________________________________________________________
long where(void);
Description:
This function will return the current file position.
Returns:
nonzero on error.
See Also:
CLASS NAME: STACK PARENT: NONE
IMPORTANT CHILDREN: NONE
Definition:
class STACK
{
public:
STACK();
int pop(void);
void push(int v);
int empty(void);
private:
int location;
int stack[STACK_SIZE];
};
Description:
Stack sets up a stack(FIFO) to hold integers. This stack may be upto
STACK_SIZE in length.
Data Members:
NONE
Member Functions:
STACK();
CONSTRUCTOR - sets up a empty stack.
int pop(void);
Pops an integer from the stack.
void push(int v);
Pushes an integer onto the stack.
int empty(void);
This function allows you to tell if a stack is empty. It returns
nonzero if the stack has items, zero if there are none.
Glossary
BAUD - the communication rate between two devices. Baud rates usually
range from 300 to 38400 baud.
CARRIER - is a signal generated by a remote modem to say that it is
still on-line. In any serious communications program carrier must be
repeatedly checked to ensure the remote modem is still connected.
CREATOR - a file ID used by some operating systems(most notably the
Mac) that allows data files to know "who created them."
DATA CONTAINER - A dynamic holding area for data that can shrink or
grow to handle the amount of data sent. Data containers usually store
data in some predetermined way.
DTR - The software on/off switch for a modem. If DTR is lowered the
modem hangs up and will not accept any commands until the DTR is
raised.
DYNAMIC - Able to change to meet the situation at hand. Dynamic
containers only take up the amount of memory needed.
FALSE - A value is said to be false when it contains a zero.
FIFO - "First In First Out" a way of describing how a data container
works, usually associated with a queue.
FILE TYPE - some operating systems(most notably the Mac) allow you to
assign a file type to any file you open.
HAYES COMPAT - A type of modem that understands the hayes AT style
command. A hayes modem receives all its commands over the data lines,
rather than the special control lines.
INTERRUPT - When the computer stops doing what it was doing to handle
something that has happened.
INTERRUPT DEVICE - A device that stops the computers processing to
handle its changed state.
LINE NOISE - Errors that commonly occur in data communication caused by
bad phone lines.
LIFO - "Last In First Out" a way of describing how a data container
works, usually associated with a stack.
LINKED LIST - A sort of dynamic array. A linked list holds a series of
elements in some predetermined order.
MODAL-A window that once on your screen is the only thing that you can
access until it is "dismissed."
MODELESS-A window that can be moved to the background by clicking
another window on the screen.
POLLED DEVICE - A device that generates no interrupt when its state
changes, but rather must be polled to determine if it is ready. All
devices in MULTI-APP are polled.
QUEUE - A data container commonly put between to devices of differing
speeds. A queue will accept information and release it in the same
order as it got it. Think of a queue as a one-way street, only one
entrance and only one exit.
STACK - A data container commonly used when you want to leave something
the same way you came. A stack will accept information and release the
last item you entered, then the 2nd to last and so on. Think of a
stack as a restaurant plate holder, you
can only get the plate on the top. If you want to get the bottom
plate you must remove all plates.
TRUE - A value is said to be true when it holds any value other than
zero.